home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / zgeevx.z / zgeevx
Encoding:
Text File  |  2002-10-03  |  10.0 KB  |  265 lines
  1.  
  2.  
  3.  
  4. ZZZZGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))                                                          ZZZZGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ZGEEVX - compute for an N-by-N complex nonsymmetric matrix A, the
  10.      eigenvalues and, optionally, the left and/or right eigenvectors
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE ZGEEVX( BALANC, JOBVL, JOBVR, SENSE, N, A, LDA, W, VL, LDVL,
  14.                         VR, LDVR, ILO, IHI, SCALE, ABNRM, RCONDE, RCONDV,
  15.                         WORK, LWORK, RWORK, INFO )
  16.  
  17.          CHARACTER      BALANC, JOBVL, JOBVR, SENSE
  18.  
  19.          INTEGER        IHI, ILO, INFO, LDA, LDVL, LDVR, LWORK, N
  20.  
  21.          DOUBLE         PRECISION ABNRM
  22.  
  23.          DOUBLE         PRECISION RCONDE( * ), RCONDV( * ), RWORK( * ), SCALE(
  24.                         * )
  25.  
  26.          COMPLEX*16     A( LDA, * ), VL( LDVL, * ), VR( LDVR, * ), W( * ),
  27.                         WORK( * )
  28.  
  29. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  30.      These routines are part of the SCSL Scientific Library and can be loaded
  31.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  32.      directs the linker to use the multi-processor version of the library.
  33.  
  34.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  35.      4 bytes (32 bits). Another version of SCSL is available in which integers
  36.      are 8 bytes (64 bits).  This version allows the user access to larger
  37.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  38.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  39.      only one of the two versions; 4-byte integer and 8-byte integer library
  40.      calls cannot be mixed.
  41.  
  42. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  43.      ZGEEVX computes for an N-by-N complex nonsymmetric matrix A, the
  44.      eigenvalues and, optionally, the left and/or right eigenvectors.
  45.      Optionally also, it computes a balancing transformation to improve the
  46.      conditioning of the eigenvalues and eigenvectors (ILO, IHI, SCALE, and
  47.      ABNRM), reciprocal condition numbers for the eigenvalues (RCONDE), and
  48.      reciprocal condition numbers for the right
  49.      eigenvectors (RCONDV).
  50.  
  51.      The right eigenvector v(j) of A satisfies
  52.                       A * v(j) = lambda(j) * v(j)
  53.      where lambda(j) is its eigenvalue.
  54.      The left eigenvector u(j) of A satisfies
  55.                    u(j)**H * A = lambda(j) * u(j)**H
  56.      where u(j)**H denotes the conjugate transpose of u(j).
  57.  
  58.      The computed eigenvectors are normalized to have Euclidean norm equal to
  59.      1 and largest component real.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ZZZZGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))                                                          ZZZZGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      Balancing a matrix means permuting the rows and columns to make it more
  75.      nearly upper triangular, and applying a diagonal similarity
  76.      transformation D * A * D**(-1), where D is a diagonal matrix, to make its
  77.      rows and columns closer in norm and the condition numbers of its
  78.      eigenvalues and eigenvectors smaller.  The computed reciprocal condition
  79.      numbers correspond to the balanced matrix.  Permuting rows and columns
  80.      will not change the condition numbers (in exact arithmetic) but diagonal
  81.      scaling will.  For further explanation of balancing, see section 4.10.2
  82.      of the LAPACK Users' Guide.
  83.  
  84.  
  85. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  86.      BALANC  (input) CHARACTER*1
  87.              Indicates how the input matrix should be diagonally scaled and/or
  88.              permuted to improve the conditioning of its eigenvalues.  = 'N':
  89.              Do not diagonally scale or permute;
  90.              = 'P': Perform permutations to make the matrix more nearly upper
  91.              triangular. Do not diagonally scale; = 'S': Diagonally scale the
  92.              matrix, ie. replace A by D*A*D**(-1), where D is a diagonal
  93.              matrix chosen to make the rows and columns of A more equal in
  94.              norm. Do not permute; = 'B': Both diagonally scale and permute A.
  95.  
  96.              Computed reciprocal condition numbers will be for the matrix
  97.              after balancing and/or permuting. Permuting does not change
  98.              condition numbers (in exact arithmetic), but balancing does.
  99.  
  100.      JOBVL   (input) CHARACTER*1
  101.              = 'N': left eigenvectors of A are not computed;
  102.              = 'V': left eigenvectors of A are computed.  If SENSE = 'E' or
  103.              'B', JOBVL must = 'V'.
  104.  
  105.      JOBVR   (input) CHARACTER*1
  106.              = 'N': right eigenvectors of A are not computed;
  107.              = 'V': right eigenvectors of A are computed.  If SENSE = 'E' or
  108.              'B', JOBVR must = 'V'.
  109.  
  110.      SENSE   (input) CHARACTER*1
  111.              Determines which reciprocal condition numbers are computed.  =
  112.              'N': None are computed;
  113.              = 'E': Computed for eigenvalues only;
  114.              = 'V': Computed for right eigenvectors only;
  115.              = 'B': Computed for eigenvalues and right eigenvectors.
  116.  
  117.              If SENSE = 'E' or 'B', both left and right eigenvectors must also
  118.              be computed (JOBVL = 'V' and JOBVR = 'V').
  119.  
  120.      N       (input) INTEGER
  121.              The order of the matrix A. N >= 0.
  122.  
  123.      A       (input/output) COMPLEX*16 array, dimension (LDA,N)
  124.              On entry, the N-by-N matrix A.  On exit, A has been overwritten.
  125.              If JOBVL = 'V' or JOBVR = 'V', A contains the Schur form of the
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ZZZZGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))                                                          ZZZZGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))
  137.  
  138.  
  139.  
  140.              balanced version of the matrix A.
  141.  
  142.      LDA     (input) INTEGER
  143.              The leading dimension of the array A.  LDA >= max(1,N).
  144.  
  145.      W       (output) COMPLEX*16 array, dimension (N)
  146.              W contains the computed eigenvalues.
  147.  
  148.      VL      (output) COMPLEX*16 array, dimension (LDVL,N)
  149.              If JOBVL = 'V', the left eigenvectors u(j) are stored one after
  150.              another in the columns of VL, in the same order as their
  151.              eigenvalues.  If JOBVL = 'N', VL is not referenced.  u(j) =
  152.              VL(:,j), the j-th column of VL.
  153.  
  154.      LDVL    (input) INTEGER
  155.              The leading dimension of the array VL.  LDVL >= 1; if JOBVL =
  156.              'V', LDVL >= N.
  157.  
  158.      VR      (output) COMPLEX*16 array, dimension (LDVR,N)
  159.              If JOBVR = 'V', the right eigenvectors v(j) are stored one after
  160.              another in the columns of VR, in the same order as their
  161.              eigenvalues.  If JOBVR = 'N', VR is not referenced.  v(j) =
  162.              VR(:,j), the j-th column of VR.
  163.  
  164.      LDVR    (input) INTEGER
  165.              The leading dimension of the array VR.  LDVR >= 1; if JOBVR =
  166.              'V', LDVR >= N.
  167.  
  168.              ILO,IHI (output) INTEGER ILO and IHI are integer values
  169.              determined when A was balanced.  The balanced A(i,j) = 0 if I > J
  170.              and J = 1,...,ILO-1 or I = IHI+1,...,N.
  171.  
  172.      SCALE   (output) DOUBLE PRECISION array, dimension (N)
  173.              Details of the permutations and scaling factors applied when
  174.              balancing A.  If P(j) is the index of the row and column
  175.              interchanged with row and column j, and D(j) is the scaling
  176.              factor applied to row and column j, then SCALE(J) = P(J),    for
  177.              J = 1,...,ILO-1 = D(J),    for J = ILO,...,IHI = P(J)     for J =
  178.              IHI+1,...,N.  The order in which the interchanges are made is N
  179.              to IHI+1, then 1 to ILO-1.
  180.  
  181.      ABNRM   (output) DOUBLE PRECISION
  182.              The one-norm of the balanced matrix (the maximum of the sum of
  183.              absolute values of elements of any column).
  184.  
  185.      RCONDE  (output) DOUBLE PRECISION array, dimension (N)
  186.              RCONDE(j) is the reciprocal condition number of the j-th
  187.              eigenvalue.
  188.  
  189.      RCONDV  (output) DOUBLE PRECISION array, dimension (N)
  190.              RCONDV(j) is the reciprocal condition number of the j-th right
  191.              eigenvector.
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ZZZZGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))                                                          ZZZZGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      WORK    (workspace/output) COMPLEX*16 array, dimension (LWORK)
  207.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  208.  
  209.      LWORK   (input) INTEGER
  210.              The dimension of the array WORK.  If SENSE = 'N' or 'E', LWORK >=
  211.              max(1,2*N), and if SENSE = 'V' or 'B', LWORK >= N*N+2*N.  For
  212.              good performance, LWORK must generally be larger.
  213.  
  214.              If LWORK = -1, then a workspace query is assumed; the routine
  215.              only calculates the optimal size of the WORK array, returns this
  216.              value as the first entry of the WORK array, and no error message
  217.              related to LWORK is issued by XERBLA.
  218.  
  219.      RWORK   (workspace) DOUBLE PRECISION array, dimension (2*N)
  220.  
  221.      INFO    (output) INTEGER
  222.              = 0:  successful exit
  223.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  224.              > 0:  if INFO = i, the QR algorithm failed to compute all the
  225.              eigenvalues, and no eigenvectors or condition numbers have been
  226.              computed; elements 1:ILO-1 and i+1:N of W contain eigenvalues
  227.              which have converged.
  228.  
  229. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  230.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  231.  
  232.      This man page is available only online.
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.